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iRobot Roomba® Open Interface Overview 


The Roomba Open Interface (Ol) is a software interface for controlling and manipulating Roomba’s 
behavior. The software interface lets you manipulate Roomba’s behavior and read its sensors through a 
series of commands, including mode commands, actuator commands, song commands, and sensor 
commands that you send to the Roomba’s serial port by way of a PC or microcontroller that is connected 
to the Mini-DIN connector. 


Physical Connections 


To use the Ol, a processor capable of generating serial commands such as a PC or a microcontroller must 
be connected to the external Mini-DIN connector on Roomba. This connector provides two-way, serial 
communication at TTL (0 - 5V) levels. The connector also provides an unregulated direct connection to 
Roomba’s battery, which you can use to power the OI applications. The Mini-DIN connector is located on 
the top of Roomba, beneath the snap-on decorative cover. 


Roomba’s External Serial Port Mini-DIN Connector Pinout 


This diagram shows the pinout of the top view of the female connector in Roomba. Note that pins 5, 6, 
and 7 are towards the bottom of Roomba. 


Pin Name Description 

1 Vpwr Roomba battery + (unregulated) 
2 Vpwr Roomba battery + (unregulated) 
3 RXD 0 - 5V Serial input to Roomba 

4 TXD 0 - 5V Serial output from Roomba 
5 BRC Baud Rate Change 

6 GND Roomba battery ground 

7 GND Roomba battery ground 


Since the RXD and TXD pins use 0 - 5V logic voltage and the PC serial ports use different voltages (rs232 
levels), it is necessary to shift voltage levels. To do this, use an iRobot Roomba serial cable rather than a 
normal serial cable, as the iRobot Roomba serial cable contains all of the necessary hardware to shift the 
voltage levels, whereas the normal serial cable does not. 
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Serial Port Settings 


Baud: 115200 or 19200 (see below) 
Data bits: 8 

Parity: None 

Stop bits: 1 

Flow control: None 


By default, Roomba communicates at 115200 baud. If you are using a microcontroller that does not 
support 115200 baud, there are two ways to force Roomba to switch to 19200: 


Method 1: 


When powering on Roomba, hold down the Clean/Power button. After about 10 seconds, Roomba plays a 
tune of descending pitches. Roomba will communicate at 19200 baud until the power is turned off, the 
battery is removed and reinserted, the battery voltage falls below the minimum required for processor 
operation, or the baud rate is explicitly changed by way of the Ol. 


Method 2: 


Use the Baud Rate Change pin (pin 5 on the Mini-DIN connector) to change Roomba’s baud rate. After 
turning on Roomba, wait 2 seconds and then pulse the Baud Rate Change low three times. Each pulse 
should last between 50 and 500 milliseconds. Roomba will communicate at 19200 baud until the 
processor loses battery power or the baud rate is explicitly changed by way of the Ol. 
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Roomba Open Interface Modes 


The Roomba OI! has four operating modes: Off, Passive, Safe, and Full. After a battery change or when 
power is first turned on, the OI is in “off” mode. When it is off, the OI listens at the default baud rate 
(115200 or 19200 - see Serial Port Settings above) for an Ol Start command. Once it receives the Start 
command, you can enter into any one of the four operating modes by sending a mode command to the 
Ol. You can also switch between operating modes at any time by sending a command to the OI for the 
operating mode that you want to use. 


Passive Mode 


Upon sending the Start command or any one of the cleaning mode commands (e.g., Spot, Clean, Seek 
Dock), the OI enters into Passive mode. When the OI is in Passive mode, you can request and receive 
sensor data using any of the sensor commands, but you cannot change the current command parameters 
for the actuators (motors, speaker, lights) to something else. To change how one of the actuators 
operates, you must switch from Passive mode to Full mode or Safe mode. 


While in Passive mode, you can read Roomba’s sensors, watch Roomba perform a cleaning cycle, and 
charge the battery. 


Safe Mode 


When you send a Safe command to the OI, Roomba enters into Safe mode. Safe mode gives you full 
control of Roomba, with the exception of the following safety-related conditions: 


e Detection of a cliff while moving forward (or moving backward with a small turning radius, less than 
one robot radius). 

e Detection of a wheel drop (on any wheel). 

e Charger plugged in and powered. 


Should one of the above safety-related conditions occur while the OI is in Safe mode, Roomba stops all 
motors and reverts to the Passive mode. 


If no commands are sent to the OI when in Safe mode, Roomba waits with all motors and LEDs off and 
does not respond to button presses or other sensor input. 


Note that charging terminates when you enter Safe Mode. 
Full Mode 


When you send a Full command to the OI, Roomba enters into Full mode. Full mode gives you complete 
control over Roomba, all of its actuators, and all of the safety-related conditions that are restricted when 
the OI is in Safe mode, as Full mode shuts off the cliff, wheel-drop and internal charger safety features. 
To put the OI back into Safe mode, you must send the Safe command. 


If no commands are sent to the OI when in Full mode, Roomba waits with all motors and LEDs off and 
does not respond to button presses or other sensor input. 


Note that charging terminates when you enter Full Mode. 
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Open Interface Command Reference 


The following is a list of all of Roomba’s Open Interface commands. Each command starts with a one- 
byte opcode. Some of the commands must be followed by data bytes. All of Roomba’s O! commands 
including their required data bytes are described below. 


NOTE: 


Always send the required number of data bytes for the command, otherwise, the processor will enter and 
remain in a “waiting” state until all of the required data bytes are received. 


Getting Started Commands 
The following commands start the Open Interface and get it ready for use. 


Start Opcode: 128 Data Bytes: 0 


This command starts the O!|. You must always send the Start command before sending any other 
commands to the Ol. 


e Serial sequence: [128]. 
e Available in modes: Passive, Safe, or Full 


e Changes mode to: Passive. Roomba beeps once to acknowledge it is starting from “off” mode. 


Baud Opcode: 129 Data Bytes: 1 


This command sets the baud rate in bits per second (bps) at which Ol commands and data are sent 
according to the baud code sent in the data byte. The default baud rate at power up is 115200 bps, but 
the starting baud rate can be changed to 19200 by holding down the Clean button while powering on 
Roomba until you hear a sequence of descending tones. Once the baud rate is changed, it persists until 
Roomba is power cycled by pressing the power button or removing the battery, or when the battery 
voltage falls below the minimum required for processor operation. You must wait 100ms after sending 
this command before sending additional commands at the new baud rate. 


e Serial sequence: [129][Baud Code] 

e Available in modes: Passive, Safe, or Full 
e Changes mode to: No Change 

e Baud data byte 1: Baud Code (0 - 11) 
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Baud Code Baud Rate in BPS 


0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
1 
1 


115200 


Mode Commands 


Roomba has four operating modes: Off, Passive, Safe, and Full. Roomba powers on in the Off mode. The 
following commands change Roomba’s O! mode. 


Safe Opcode: 131 Data Bytes: 0 


This command puts the O! into Safe mode, enabling user control of Roomba. It turns off all LEDs. The Ol 
can be in Passive, Safe, or Full mode to accept this command. If a safety condition occurs (see above) 
Roomba reverts automatically to Passive mode. 


e Serial sequence: [131] 
e Available in modes: Passive, Safe, or Full 


e Changes mode to: Safe 


Note: The effect and usage of the Control command (130) are identical to the Safe command. 


Full Opcode: 132 Data Bytes: 0 


This command gives you complete control over Roomba by putting the OI into Full mode, and turning off 
the cliff, wheel-drop and internal charger safety features. That is, in Full mode, Roomba executes any 
command that you send it, even if the internal charger is plugged in, or command triggers a cliff or wheel 
drop condition. 


e Serial sequence: [132] 
e Available in modes: Passive, Safe, or Full 


e Changes mode to: Full 


Note: Use the Start command (128) to change the mode to Passive. 
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Cleaning Commands 


The following are commands to start Roomba’s built-in cleaning modes and set the clock and schedule. 


Clean Opcode: 135 Data Bytes: 0 
This command starts the default cleaning mode. 

e Serial sequence: [135] 

e Available in modes: Passive, Safe, or Full 

e Changes mode to: Passive 

Max Opcode: 136 Data Bytes: 0 
This command starts the Max cleaning mode. 

e Serial sequence: [136] 

e Available in modes: Passive, Safe, or Full 

e Changes mode to: Passive 

Spot Opcode: 134 Data Bytes: 0 
This command starts the Spot cleaning mode. 

e Serial sequence: [134] 

e Available in modes: Passive, Safe, or Full 

e Changes mode to: Passive 

Seek Dock Opcode: 143 Data Bytes: 0 
This command sends Roomba to the dock. 

e Serial sequence: [143] 

e Available in modes: Passive, Safe, or Full 

e Changes mode to: Passive 

Schedule Opcode: 167 Data Bytes: 15 


This command sends Roomba a new schedule. To disable scheduled cleaning, send all Os. 


e Serial sequence: [167] [Days] [Sun Hour] [Sun Minute] [Mon Hour] [Mon Minute] [Tue Hour] [Tue 
Minute] [Wed Hour] [Wed Minute] [Thu Hour] [Thu Minute] [Fri Hour] [Fri Minute] [Sat Hour] [Sat 


Minute] 


e Available in modes: Passive, Safe, or Full. 


e If Roomba’s schedule or clock button is pressed, this command will be ignored. 


e Changes mode to: No change 


e Times are sent in 24 hour format. Hour (0-23) Minute (0-59) 
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Days 
Bit [7 ier Be 
Value [Reserved 


Example: 
To schedule the robot to clean at 3:00 PM on Wednesdays and 10:36 AM on Fridays, send: [167] [40] [0] 
[0] [0] [0] [0] [0] [15] [0] [0] [0] [10] [36] [0] [0] 


To disable scheduled cleaning, send: [167] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] 


Set Day/ Time Opcode: 168 Data Bytes: 3 


This command sets Roomba’'s clock. 

e Serial sequence: [168] [Day] [Hour] [Minute] 

e Available in modes: Passive, Safe, or Full. 

e If Roomba’s schedule or clock button is pressed, this command will be ignored. 
e Changes mode to: No change 

e Time is sent in 24 hour format. Hour (0-23) Minute (0-59) 


Code Day 

Sunday 
Monday 
Tuesday 
Wednesday 
Thursday 
Friday 
Saturday 


AUBWNF O 


Power Opcode: 133 Data Bytes: 0 


This command powers down Roomba. The OI can be in Passive, Safe, or Full mode to accept this 
command. 


e Serial sequence: [133] 
e Available in modes: Passive, Safe, or Full 


e Changes mode to: Passive 
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Actuator Commands 


The following commands control Roomba’s actuators: wheels, brushes, vacuum, speaker, LEDS, and 
buttons. 


Drive Opcode: 137 Data Bytes: 4 


This command controls Roomba’s drive wheels. It takes four data bytes, interpreted as two 16-bit signed 
values using two's complement. The first two bytes specify the average velocity of the drive wheels in 
millimeters per second (mm/s), with the high byte being sent first. The next two bytes specify the radius 
in millimeters at which Roomba will turn. The longer radii make Roomba drive straighter, while the 
shorter radii make Roomba turn more. The radius is measured from the center of the turning circle to the 
center of Roomba. A Drive command with a positive velocity and a positive radius makes Roomba drive 
forward while turning toward the left. A negative radius makes Roomba turn toward the right. Special 
cases for the radius make Roomba turn in place or drive straight, as specified below. A negative velocity 
makes Roomba drive backward. 


NOTE: 


Internal and environmental restrictions may prevent Roomba from accurately carrying out some drive 
commands. For example, it may not be possible for Roomba to drive at full speed in an arc with a large 
radius of curvature. 


e Serial sequence: [137] [Velocity high byte] [Velocity low byte] [Radius high byte] [Radius low byte] 
e Available in modes: Safe or Full 
e Changes mode to: No Change 
e Velocity (-500 - 500 mm/s) 
e Radius (-2000 - 2000 mm) 
Special cases: 
Straight = 32768 or 32767 = hex 8000 or 7FFF 
Turn in place clockwise = -1 
Turn in place counter-clockwise = 1 
Example: 


To drive in reverse at a velocity of -200 mm/s while turning at a radius of 500mm, send the following 
serial byte sequence: 


[137] [255] [56] [1] [244] 
Velocity = -200 = hex FF38 = [hex FF] [hex 38] = [255] [56] 
Radius = 500 = hex 01F4 = [hex 01] [hex F4] = [1] [244] 
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Drive Direct Opcode: 145 Data Bytes: 4 


This command lets you control the forward and backward motion of Roomba’s drive wheels 
independently. It takes four data bytes, which are interpreted as two 16-bit signed values using two's 
complement. The first two bytes specify the velocity of the right wheel in millimeters per second (mm/s), 
with the high byte sent first. The next two bytes specify the velocity of the left wheel, in the same 
format. A positive velocity makes that wheel drive forward, while a negative velocity makes it drive 
backward. 


e Serial sequence: [145] [Right velocity high byte] [Right velocity low byte] [Left velocity high byte] 
[Left velocity low byte] 


e Available in modes: Safe or Full 

e Changes mode to: No Change 

e Right wheel velocity (-500 - 500 mm/s) 
e Left wheel velocity (-500 - 500 mm/s) 


Drive PWM Opcode: 146 Data Bytes: 4 


This command lets you control the raw forward and backward motion of Roomba’s drive wheels 
independently. It takes four data bytes, which are interpreted as two 16-bit signed values using two’s 
complement. The first two bytes specify the PWM of the right wheel, with the high byte sent first. The 
next two bytes specify the PWM of the left wheel, in the same format. A positive PWM makes that wheel 
drive forward, while a negative PWM makes it drive backward. 


e Serial sequence: [146] [Right PWM high byte] [Right PWM low byte] [Left PWM high byte] [Left PWM 
low byte] 


e Available in modes: Safe or Full 
e Changes mode to: No Change 
e Right wheel PWM (-255 - 255) 
e Left wheel PWM (-255 - 255) 


Motors Opcode: 138 Data Bytes: 1 


This command lets you control the forward and backward motion of Roomba’s main brush, side brush, 
and vacuum independently. Motor velocity cannot be controlled with this command, all motors will run at 
maximum speed when enabled. The main brush and side brush can be run in either direction. The 
vacuum only runs forward. 


Serial sequence: [138] [Motors] 

e Available in modes: Safe or Full 

e Changes mode to: No Change 

e Bits 0-2: 0 = off, 1 = on at 100% pwm duty cycle 


e Bits 3 & 4: 0 = motor’s default direction, 1 = motor’s opposite direction. Default direction for the side 
brush is counterclockwise. Default direction for the main brush/flapper is inward. 
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ai ee 


Value | Reserved Main i Main Vacuum eas —| 
Brush Brush Brush 
Direction 


Example: 


To turn on the main brush inward and the side brush clockwise, send: [138] [13] 


PWM Motors Opcode: 144 Data Bytes: 3 


This command lets you control the speed of Roomba’s main brush, side brush, and vacuum 
independently. With each data byte, you specify the duty cycle for the low side driver (max 128). For 
example, if you want to control a motor with 25% of battery voltage, choose a duty cycle of 128 * 25% 
= 32. The main brush and side brush can be run in either direction. The vacuum only runs forward. 
Positive speeds turn the motor in its default (cleaning) direction. Default direction for the side brush is 
counterclockwise. Default direction for the main brush/flapper is inward. 


Serial sequence: [144] [Main Brush PWM] [Side Brush PWM] [Vacuum PWM] 
e Available in modes: Safe or Full 

e Changes mode to: No Change 

e Main Brush and Side Brush duty cycle (-127 - 127) 

e Vacuum duty cycle (0 - 127) 


LEDs Opcode: 139 Data Bytes: 3 


This command controls the LEDs common to all models of Roomba 500. The Clean/Power LED is 
specified by two data bytes: one for the color and the other for the intensity. 


e Serial sequence: [139] [LED Bits] [Clean/Power Color] [Clean/Power Intensity] 
e Available in modes: Safe or Full 

e Changes mode to: No Change 

e LED Bits (0 - 255) 


Home and Spot use green LEDs: 0 = off, 1 = on 

Check Robot uses an orange LED. 

Debris uses a blue LED. 

Clean/ Power uses a bicolor (red/green) LED. The intensity and color of this LED can be controlled with 
8-bit resolution. 


LED Bits (0-255) 
[Bit [7 [6 [5 


| 4 3 2 1 0 
Value | Reserved Check Dock Spot Debris 
Robot 


Clean/ Power LED Color (0 - 255) 
0 = green, 255 = red. Intermediate values are intermediate colors (orange, yellow, etc). 
Clean/ Power LED Intensity (0 - 255) 


0 = off, 255 = full intensity. Intermediate values are intermediate intensities. 
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Example: 


To turn on the Home LED and light the Clean/Power LED green at half intensity, send the serial byte 
sequence [139] [4] [0] [128]. 


Scheduling LEDS Opcode: 162 Data Bytes: 2 


This command controls the state of the scheduling LEDs present on the Roomba 560 and 570. 
Serial sequence: [162] [Weekday LED Bits][Scheduling LED Bits] 


Available in modes: Safe or Full 


Changes mode to: No Change 
Weekday LED Bits (0 - 255) 
Scheduling LED Bits (0 - 255) 
All use red LEDs: 0 = off, 1 = on 


Weekday LED Bits 
Bit__[7 2 —— ae ee 
Value | Reserved 
Scheduling LED Bits 
Bit__[7 6 5 ee ee es Od 
Value | Reserved Schedule | Clock Colon (:) 
Digit LEDs Raw Opcode: 163 Data Bytes: 4 
This command controls the four 7 segment A 
displays on the Roomba 560 and 570. Bearer arernrerereey 
e Serial sequence: [163] [Digit 3 Bits] [Digit 2 
Bits] [Digit 1 Bits] [Digit 0 Bits] F B 
e Available in modes: Safe or Full G6 
e Changes mode to: No Change ———- 
e Digit N Bits (0 - 255) E c 
e All use red LEDs: 0 = off, 1 = on. Digits are 
ordered from left to right on the robot 
3,2,1,0. or 


Digit N Bits 


Bit [7 a 
Value | Reserved |G JF CE CU CTA 


Digit LEDs ASCII Opcode: 164 Data Bytes: 4 


This command controls the four 7 segment displays on the Roomba 560 and 570 using ASCII character 
codes. Because a 7 segment display is not sufficient to display alphabetic characters properly, all 
characters are an approximation, and not all ASCII codes are implemented. 


e Serial sequence: [164] [Digit 3 ASCII] [Digit 2 ASCII] [Digit 1 ASCII] [Digit 0 ASCII] 
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e Available in modes: Safe or Full 
e Changes mode to: No Change 
e Digit N ASCII (32 - 126) 
e All use red LEDs. Digits are ordered from left to right on the robot 3,2,1,0. 
Example: 
To write ABCD to the display, send the serial byte sequence: [164] [65] [66] [67] [68] 
Table of ASCII codes: 
Code Display | Code Display | Code Display | Code Display 


>U-ON<xs< 


- 
i) 


r 


< 
> 
? 
A { 
B | 
C i 
D 
E 


Buttons Opcode: 165 Data Bytes: 1 


This command lets you push Roomba’s buttons. The buttons will automatically release after 1/6" of a 
second. 


e Serial sequence: [165] [Buttons] 

e Available in modes: Passive, Safe, or Full 

e Changes mode to: No Change 

e Buttons (0-255) 1 = Push Button, 0 = Release Button 


A 
Value Schedule 
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Song Opcode: 140 Data Bytes: 2N+2, 


where N is the number of notes in the song 


This command lets you specify up to four songs to the OI that you can play at a later time. Each song is 
associated with a song number. The Play command uses the song number to identify your song selection. 
Each song can contain up to sixteen notes. Each note is associated with a note number that uses MIDI 
note definitions and a duration that is specified in fractions of a second. The number of data bytes varies, 
depending on the length of the song specified. A one note song is specified by four data bytes. For each 
additional note within a song, add two data bytes. 


Serial sequence: [140] [Song Number] [Song Length] [Note Number 1] [Note Duration 1] [Note 
Number 2] [Note Duration 2], etc. 


Available in modes: Passive, Safe, or Full 
Changes mode to: No Change 
Song Number (0 - 4) 


The song number associated with the specific song. If you send a second Song command, using the 
same song number, the old song is overwritten. 


Song Length (1 - 16) 
The length of the song, according to the number of musical notes within the song. 
Song data bytes 3, 5, 7, etc.: Note Number (31 - 127) 


The pitch of the musical note Roomba will play, according to the MIDI note numbering scheme. The 
lowest musical note that Roomba will play is Note #31. Roomba considers all musical notes outside 
the range of 31 - 127 as rest notes, and will make no sound during the duration of those notes. 


Song data bytes 4, 6, 8, etc.: Note Duration (0 - 255) 


The duration of a musical note, in increments of 1/64‘ of a second. Example: a half-second long 
musical note has a duration value of 32. 
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Number Note Frequency | Number Note Frequency | Number Note Frequency 


Play Opcode: 141 Data Bytes: 1 


This command lets you select a song to play from the songs added to Roomba using the Song command. 
You must add one or more songs to Roomba using the Song command in order for the Play command to 
work. 


e Serial sequence: [141] [Song Number] 
e Available in modes: Safe or Full 

e Changes mode to: No Change 

e Song Number (0 - 4) 


The number of the song Roomba is to play. 
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Input Commands 

The following commands let you read the state of Roomba’s built-in sensors and some internal state 
variables. Roomba updates these values internally every 15 ms. Do not send these commands more 
frequently than that. 


Sensors Opcode: 142 Data Bytes: 1 


This command requests the OI to send a packet of sensor data bytes. There are 58 different sensor data 
packets. Each provides a value of a specific sensor or group of sensors. 


For more information on sensor packets, refer to the next section, “Roomba Open Interface Sensors 
Packets”. 


e Serial sequence: [142] [Packet |D] 
e Available in modes: Passive, Safe, or Full 
e Changes mode to: No Change 


e Packet ID: Identifies which of the 58 sensor data packets should be sent back by the OI. A value of 
100 indicates a packet with all of the sensor data. Values of 0 through 6 and 101 through 107 
indicate specific subgroups of the sensor data. 


Query List Opcode: 149 Data Bytes: N + 1, 
where N is the number of packets requested. 


This command lets you ask for a list of sensor packets. The result is returned once, as in the Sensors 
command. The robot returns the packets in the order you specify. 

e Serial sequence: [149][Number of Packets][Packet 1D 1][Packet ID 2]...[Packet 1D N] 

e Available in modes: Passive, Safe, or Full 

e Changes modes to: No Change 

Example: 

To get the state of the bumpers and the virtual wall sensor, send the following sequence: 
[149] [2] [7] [13] 


Stream Opcode: 148 Data Bytes: N + 1, 
where N is the number of packets requested. 


This command starts a stream of data packets. The list of packets requested is sent every 15 ms, which 
is the rate Roomba uses to update data. 


This method of requesting sensor data is best if you are controlling Roomba over a wireless network 
(which has poor real-time characteristics) with software running on a desktop computer. 


e Serial sequence: [148] [Number of packets] [Packet 1D 1] [Packet ID 2] [Packet ID 3] etc. 
e Available in modes: Passive, Safe, or Full 


e Changes mode to: No Change 
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The format of the data returned is: 


[19][N-bytes][Packet 1D 1][Packet 1 data...][Packet ID 2][Packet 2 data...][Checksum] 


N-bytes is the number of bytes between the n-bytes byte and the checksum. 


The checksum is a 1-byte value. It is the 8-bit complement of all of the bytes between the header and 


the checksum. That is, if you add all of the bytes after the checksum, and the checksum, the low byte of 


the result will be 0. 


Example: 


To get data from Roomba's left cliff signal (packet 29) and virtual wall sensor (packet 13), send the 
following command string to Roomba: 


[148] [2] [29] [13] 


NOTE: 


The left cliff signal is a 2-byte packet and the virtual wall is a 1-byte packet. 


Roomba starts streaming data that looks like this: 


19 5 29 2 25 13 0 182 
header | n-bytes | packetID1 | Packet data 1(2 bytes) | packetID 2 | packet data 2 (1 byte) | Checksum 
NOTE: 


Checksum computation: (5 + 29 + 2 + 25+ 13+ 0 + 182) = 256 and (256 & OxFF) = 0. 


In the above stream segment, Roomba’s left cliff signal value was 549 (0x0225) and there was no virtual 
wall signal. 


It is up to you not to request more data than can be sent at the current baud rate in the 15 ms time slot. 


For example, at 57600 baud, a maximum of 86 bytes can be sent in 15 ms: 


15 ms / 10 bits (8 data + start + stop) * 57600 = 86.4 


If more data is requested, the data stream will eventually become corrupted. This can be confirmed by 
checking the checksum. 


The header byte and checksum can be used to align your receiving program with the data. All data 


chunks start with 19 and end with the 1-byte checksum. 


Pause/ Resume Stream 


Opcode: 150 


Data Bytes: 1 


This command lets you stop and restart the steam without clearing the list of requested packets. 


e Serial sequence: [150][Stream State] 


e Available in modes: Passive, Safe, or Full 


e Changes modes to: No Change 


e Range: 0-1 


An argument of 0 stops the stream without clearing the list of requested packets. An argument of 1 


starts the stream using the list of packets last requested. 
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Roomba Open Interface Sensor Packets 


Roomba sends back one of 58 different sensor data packets, depending on the value of the packet data 
byte, when responding to a Sensors command, Query List command, or Stream command's request for a 
packet of sensor data bytes. Some packets contain groups of other packets. Some of the sensor data 
values are 16 bit values. 


Most of the packets (numbers 7 - 58) contain the value of a single sensor or variable, which can be 
either 1 byte or 2 bytes. Two byte packets correspond to 16-bit values, sent high byte first. 


Some of the packets (0-6, 100-107) contain groups of the single-value packets. 


Group Packet ID Packet Size Contains Packets 


Bumps and Wheel Drops Packet I D: 7 Data Bytes: 1, unsigned 


The state of the bumper (0 = no bump, 1 = bump) and wheel drop sensors (0 = wheel raised, 1 = wheel 
dropped) are sent as individual bits. 


Range: 0 - 15 


Value rasan Re Rea sce ae 
Drop Drop Left? Right? 
Left? Right? 


Wall Packet ID: 8 Data Bytes: 1, unsigned 


The state of the wall sensor is sent as a 1 bit value (0 = no wall, 1 = wall seen). 


Range: 0 - 1 


Cliff Left Packet ID: 9 Data Bytes: 1, unsigned 


The state of the cliff sensor on the left side of Roomba is sent as a 1 bit value (0 = no cliff, 1 = cliff). 


Range: 0 - 1 


Cliff Front Left Packet ID: 10 Data Bytes: 1, unsigned 


The state of the cliff sensor on the front left of Roomba is sent as a 1 bit value (0 = no cliff, 1 = cliff). 
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Range: 0 - 1 


Cliff Front Right Packet ID: 11 Data Bytes: 1, unsigned 


The state of the cliff sensor on the front right of Roomba is sent as a 1 bit value (0 = no cliff, 1 = cliff) 


Range: 0- 1 


Cliff Right Packet ID: 12 Data Bytes: 1, unsigned 


The state of the cliff sensor on the right side of Roomba is sent as a 1 bit value (0 = no cliff, 1 = cliff) 


Range: 0 - 1 


Virtual Wall Packet ID: 13 Data Bytes: 1, unsigned 


The state of the virtual wall detector is sent as a 1 bit value (0 = no virtual wall detected, 1 = virtual wall 
detected). 


Range: 0 - 1 


Wheel Overcurrents Packet ID: 14 Data Bytes: 1, unsigned 


The state of the four wheel overcurrent sensors are sent as individual bits (0 = no overcurrent, 1 = 
overcurrent). There is no overcurrent sensor for the vacuum on Roomba 500. 


Range: 0 - 31 


Bit aes en 2 es ee 
Value RES a rg ht Main Reserved | Side 
Wheel Wheel Brush Brush 


Dirt Detect Packet IDs: 15 Data Bytes: 1 


The level of the dirt detect sensor. 
Range: 0-255 


Unused Byte Packet IDs: 16 Data Bytes: 1 


Unused bytes: One unused byte is sent after the dirt detect byte when the requested packet is 0, 1, or 6. 
The value of the unused byte is always 0. 


Range: 0 


Infrared Character Omni Packet ID: 17 Data Bytes: 1, unsigned 


This value identifies the 8-bit IR character currently being received by Roomba’s omnidirectional receiver. 
A value of 0 indicates that no character is being received. These characters include those sent by the 
Roomba Remote, the Dock, Roomba 500 Virtual Walls, Create robots using the Send-IR command, and 
user-created devices. 


Range: 0 - 255 
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Infrared Character Left Packet ID: 52 Data Bytes: 1, unsigned 


This value identifies the 8-bit IR character currently being received by Roomba’s left receiver. A value of 
0 indicates that no character is being received. These characters include those sent by the Roomba 
Remote, the Dock, Roomba 500 Virtual Walls, Create robots using the Send-IR command, and user- 
created devices. 


Range: 0 - 255 


Infrared Character Right Packet I D: 53 Data Bytes: 1, unsigned 


This value identifies the 8-bit IR character currently being received by Roomba’s right receiver. A value of 
0 indicates that no character is being received. These characters include those sent by the Roomba 
Remote, the Dock, Roomba 500 Virtual Walls, Create robots using the Send-IR command, and user- 
created devices. 


Range: 0 - 255 


Characters sent by iRobot devices: 


Dock beam configuration 


x 


”” Force Field *. 


Lighthouse beam configuration 
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s 


“ Force Field >. 


: 
' B ’ ; A _ B \ 
! a og ees a 
‘ / 1 4 ‘ 
= ra \ i.) i ‘ : 
Sent by iRobot Device | Character Value | Character Name 
IR Remote Control 129 Left 
130 Forward 
131 Right 
132 Spot 
133 Max 
134 Small 
135 Medium 
136 Large / Clean 
137 Stop 
138 Power 
139 Arc Left 
140 Arc Right 
141 Stop 
Scheduling Remote 142 Download 
143 Seek Dock 
Roomba Discovery Drive- | 240 Reserved 
on Charger 248 Red Buoy 
244 Green Buoy 
242 Force Field 
252 Red Buoy and Green Buoy 
250 Red Buoy and Force Field 
246 Green Buoy and Force Field 
254 Red Buoy, Green Buoy and Force 
Field 
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Sent by iRobot Device | Character Value | Character Name 
Roomba 500 Drive-on 160 Reserved 
Charger 161 Force Field 
164 Green Buoy 
165 Green Buoy and Force Field 
168 Red Buoy 
169 Red Buoy and Force Field 
172 Red Buoy and Green Buoy 
173 Red Buoy, Green Buoy and Force 
Field 
Roomba 500 Virtual Wall 162 Virtual Wall 
Roomba 500 Virtual Wall OLLLLOBB LLLL = Virtual Wall Lighthouse ID 
Lighthouse (assigned automatically by Roomba 
560 and 570 robots) 
1-10: Valid ID 
11: Unbound 
12-15: Reserved 
BB = Which Beam 
00 = Fence 
01 = Force Field 
10 = Green Buoy 
11 = Red Buoy 
Buttons Packet ID: 18 Data Bytes: 1, unsigned 


The state of the Roomba buttons are sent as individual bits (0 = button not pressed, 1 = button 
pressed). The day, hour, minute, clock, and scheduling buttons that exist only on Roomba 560 and 570 
will always return 0 on a robot without these buttons. 


Range: 0 - 255 
Me? a 
Value Schedule 


Distance Packet ID: 19 Data Bytes: 2, signed 


The distance that Roomba has traveled in millimeters since the distance it was last requested is sent as a 
signed 16-bit value, high byte first. This is the same as the sum of the distance traveled by both wheels 
divided by two. Positive values indicate travel in the forward direction; negative values indicate travel in 
the reverse direction. If the value is not polled frequently enough, it is capped at its minimum or 
maximum. 


Range: -32768 - 32767 


Angle Packet ID: 20 Data Bytes: 2, signed 


The angle in degrees that Roomba has turned since the angle was last requested is sent as a signed 16- 
bit value, high byte first. Counter-clockwise angles are positive and clockwise angles are negative. If the 
value is not polled frequently enough, it is capped at its minimum or maximum. 


Range: -32768 - 32767 
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Charging State Packet ID: 21 Data Bytes: 1, unsigned 


This code indicates Roomba’s current charging state. 


Range: 0-5 
Code Charging State 
0 Not charging 
1 Reconditioning Charging 
2 Full Charging 
3 Trickle Charging 
4 Waiting 
5 Charging Fault Condition 
Voltage Packet ID: 22 Data Bytes: 2, unsigned 


This code indicates the voltage of Roomba’s battery in millivolts (mV). 
Range: 0 - 65535 mV 


Current Packet ID: 23 Data Bytes: 2, signed 


The current in milliamps (mA) flowing into or out of Roomba’s battery. Negative currents indicate that the 
current is flowing out of the battery, as during normal running. Positive currents indicate that the current 
is flowing into the battery, as during charging. 


Range: -32768 - 32767 mA 


Temperature Packet ID: 24 Data Bytes: 1, signed 


The temperature of Roomba’s battery in degrees Celsius. 
Range: -128 - 127 


Battery Charge Packet ID: 25 Data Bytes: 2, unsigned 


The current charge of Roomba’s battery in milliamp-hours (mAh). The charge value decreases as the 
battery is depleted during running and increases when the battery is charged. 


Range: 0 - 65535 mAh 


Battery Capacity Packet ID: 26 Data Bytes: 2, unsigned 


The estimated charge capacity of Roomba’s battery in milliamp-hours (mAh). 
Range: 0 - 65535 mAh 


Wall Signal Packet ID: 27 Data Bytes: 2, unsigned 


The strength of the wall signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-1023. 


Cliff Left Signal Package | D: 28 Data Bytes: 2, unsigned 


The strength of the cliff left signal is returned as an unsigned 16-bit value, high byte first. 
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Range: 0-4095 


Cliff Front Left Signal Package I D: 29 Data Bytes 2, unsigned 


The strength of the cliff front left signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Cliff Front Right Signal Package ID: 30 Data Bytes 2, unsigned 


The strength of the cliff front right signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Cliff Right Signal Package ID: 31 Data Bytes 2, unsigned 


The strength of the cliff right signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Unused Packet ID: 32-33 Data Bytes, 3 
Range: 0 
Charging Sources Available Packet ID: 34 Data Bytes 1, unsigned 


Roomba’s connection to the Home Base and Internal Charger are returned as individual bits, as below. 


Range: 0-3 
1 = charging source present and powered; 0 = charging source not present or not powered. 
Bit [7 6 5 4 3 2 iss =O esl 
Value | Reserved Home Internal 
Base Charger 
Ol Mode Packet ID: 35 Data Bytes 1, unsigned 


The current O! mode is returned. See table below. 


Range: 0-3 


Number Mode 
Off 
Passive 


Safe 
Full 


Song Number Packet I D: 36 Data Bytes 1, unsigned 


The currently selected O! song is returned. 
Range: 0-15 
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Song Playing Packet ID: 37 Data Bytes 1, unsigned 


The state of the OI song player is returned. 1 = OI song currently playing; 0 = OI song not playing. 
Range: 0-1 


Number of Stream Packets Packet I D: 38 Data Bytes 1, unsigned 


The number of data stream packets is returned. 
Range: 0-108 


Requested Velocity Packet ID: 39 Data Bytes 2, signed 


The velocity most recently requested with a Drive command is returned as a signed 16-bit number, high 
byte first. 


Range: -500 - 500 mm/s 


Requested Radius Packet ID: 40 Data Bytes 2, signed 


The radius most recently requested with a Drive command is returned as a signed 16-bit number, high 
byte first. 


Range: -32768 - 32767 mm 


Requested Right Velocity Packet ID: 41 Data Bytes 2, signed 


The right wheel velocity most recently requested with a Drive Direct command is returned as a signed 
16-bit number, high byte first. 


Range: -500 - 500 mm/s 


Requested Left Velocity Packet ID: 42 Data Bytes 2, signed 


The left wheel velocity most recently requested with a Drive Direct command is returned as a signed 16- 
bit number, high byte first. 


Range: -500 - 500 mm/s 


Right Encoder Counts Packet ID: 43 Data Bytes 2, unsigned 


The cumulative number of raw right encoder counts is returned as an unsigned 16-bit number, high byte 
first. This number will roll over to 0 after it passes 65535. 


Range: 0 - 65535 


Left Encoder Counts Packet ID: 44 Data Bytes 2, unsigned 


The cumulative number of raw left encoder counts is returned as an unsigned 16-bit number, high byte 
first. This number will roll over to 0 after it passes 65535. 


Range: 0 - 65535 
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Light Bumper Package | D: 45 Data Bytes 1, unsigned 


The light bumper detections are returned as individual bits. 


Value | Reserved 


Range: 0-127 


Light Bump Left Signal Package ID: 46 Data Bytes 2, unsigned 


The strength of the light bump left signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Light Bump Front Left Signal Package ID: 47 Data Bytes 2, unsigned 


The strength of the light bump front left signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Light Bump Center Left Signal Package ID: 48 Data Bytes 2, unsigned 


The strength of the light bump center left signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Light Bump Center Right Signal Package ID: 49 Data Bytes 2, unsigned 


The strength of the light bump center right signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Light Bump Front Right Signal Package | D: 50 Data Bytes 2, unsigned 


The strength of the light bump front right signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Light Bump Right Signal Package ID: 51 Data Bytes 2, unsigned 


The strength of the light bump right signal is returned as an unsigned 16-bit value, high byte first. 
Range: 0-4095 


Left Motor Current Packet ID: 54 Data Bytes: 2, signed 


This returns the current being drawn by the left wheel motor as an unsigned 16 bit value, high byte first. 
Range: -32768 - 32767 mA 
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Right Motor Current Packet ID: 55 Data Bytes: 2, signed 


This returns the current being drawn by the right wheel motor as an unsigned 16 bit value, high byte 
first. 


Range: -32768 - 32767 mA 


Main Brush Motor Current Packet ID: 56 Data Bytes: 2, signed 


This returns the current being drawn by the main brush motor as an unsigned 16 bit value, high byte 
first. 


Range: -32768 - 32767 mA 


Side Brush Motor Current Packet ID: 57 Data Bytes: 2, signed 


This returns the current being drawn by the side brush motor as an unsigned 16 bit value, high byte first. 
Range: -32768 - 32767 mA 


Stasis Packet I D: 58 Data Bytes: 1 


The stasis caster sensor returns 1 when the robot is making forward progress and 0 when it is not. This 
always returns 0 when the robot is turning, driving backward, or not driving. 


Range: 0 - 1 
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Roomba Open Interface Commands Quick Reference 


Command Opcode | Data Bytes:1 | Data Bytes:2 | Data Bytes:3 | Data Bytes:4 | Etc. 


radius-high 


right- right- left-velocity- | left-velocity- 
velociye high | velocity-low | high low 


main-brush- | side-brush- vacuum- 
pwm pwm pwm 


= 
right-pwm- right-pwm- left-pwm- left-pwm-low 
at low high 

= 


power- 
intensity 


song-length 


weekdays scheduling- 
leds- state 


LED Data Bytes 1: LED Bits (0 - 255) 


Home and Spot use green LEDs: 0 = off, 1 = on 
Check Robot uses an orange LED. 
Debris uses a blue LED. 


Bit [7 6 5 4 a Ue eae al 
Value | Reserved Check Dock Spot Debris 
Robot 
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Clean/ Power LED 

The Clean/Power LED uses a bicolor (red/green) LED. The intensity and color of this LED can be 
controlled with 8-bit resolution. 

Clean/ Power LED Color (0 - 255) 

0 = green, 255 = red. Intermediate values are intermediate colors (orange, yellow, etc). 
Clean/ Power LED Intensity (0 - 255) 

0 = off, 255 = full intensity. Intermediate values are intermediate intensities. 


Weekday LED Bits 

Bit [7 a (Sa Se: a | 
Value | Reserved 
Scheduling LED Bits 

Bit [7 6 5 Ea (YC (Ce 
Value | Reserved Schedule Colon (:) 
Digit N Bits 

Bit [7 fe Ss fae ee Ol 
Value [ReeWEGE]G —[F_-‘{e -|D._|c |B [A _| 
Buttons 

A rE Ee 2 2 ee 
Value Schedule_| Day 


Table of ASCII codes 


Display | Cod Cod Display 
5 2 F 


>UI-ON<xS< 


- 
i) 


awe 


83, 36, 115 
84, 116 
85, 117 


< 
> 
? 
A 
B 
C 
D 
E 
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Baud Code Baud Rate in BPS 


FPrRWOON DA UBRWNF © 


115200 


Note Frequencies 


Number Note Frequency | Number Note Frequency | Number Note Frequency 


Set Schedule Days 


Bit__[7 [ee Wee. ae ie ee 
Value [[Resenedy| Sat____[Fi___[thu [Wed [Tue [Mon [Sin __ 
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Motors State 


Bit__[7 aes ee ee 


Value | Reserved Main i Main Vacuum eae —— 
Brush Brush Brush 
Direction 
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Roomba Open Interface Sensors Quick Reference 


Roomba sends back one of 58 different sensor Group Packet Sizes and Contents 
data packets in response to a Sensors 
command, depending on the value of the packet Group Packet ID Packet Size Contains Packets 


ID data byte. Some packets contain groups of 
other packets. The sensor values are specified 
below in the order in which they will be sent. 
Some of the sensor data values are 16 bit 
values. These values are sent as two bytes, high 
byte first. 


Bumps and Wheel Drops 


Bit__[7 i 


ae 
Value | Reserved Wheel Wheel Bump Bump 
Drop Drop Left? Right? 
Left? Right? 


Buttons 


a 
Schedule 


Charger Available 


Bit 7 6 5 4 3 2 
Value | Reserved one a 
Base Charger 


Overcurrents 
Bit [7 6 5 aa ce ff ee ee 
Value | Reserved Left Right Main Reserved | Side 
Wheel Wheel Brush Brush 
Charging State Codes Open Interface Modes 
Code _ Charging state Number Mode 
0 Not charging Off 
1 Reconditioning Charging Passive 
2 Full Charging Safe 
3. ‘Trickle Charging Full 
4 Waiting 
5 Charging Fault Condition 
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Light Bumper 


Value | Reserved 


iRobot Page 34 www.irobot.com 


iRobot® Roomba Open Interface (OI) Specification 


Sensor Packet Membership Table 


acket Group Membership Value Range 
Bumps Wheeldrops 
Wall 

Cliff Left 

Cliff Front Left 

Cliff Front Right 

Cliff Right 

Virtual Wall 
Overcurrents 

Dirt Detect 

Unused 1 

Ir Opcode 

Buttons 

Distance 

Angle 

Charging State 

Voltage 

Current 

Temperature 

Battery Charge 

Battery Capacity 

Wall Signal 

Cliff Left Signal 

Cliff Front Left Signal 
Cliff Front Right Signal 
Cliff Right Signal 
Unused 2 

Unused 3 

Charger Available 
Open Interface Mode 
Song Number 

Song Playing? 

Oi Stream Num Packets 
Velocity 

Radius 

Velocity Right 

Velocity Left 

Encoder Counts Left 
Encoder Counts Right 
Light Bumper 

Light Bump Left 

Light Bump Front Left 
Light Bump Center Left 
Light Bump Center Right 
Light Bump Front Right 
Light Bump Right 

Ir Opcode Left 

Ir Opcode Right 

Left Motor Current 
Right Motor Current 
Main Brush Current 
Side Brush Current -32768 - 32767 
Stasis 0-1 
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a ee ee cd 


-32768 - 32767 | mm 
-32768 - 32767 | degrees 
0-5 
0 - 65535 mV 
-32768 - 32767 | mA 
-128 - 127 deg C 
0 - 65535 mAh 
0 - 65535 mAh 
0 - 4095 
0 - 4095 
0 - 4095 
0 - 4095 
0 - 4095 


ooooo0co0co0co0o0co0co0cocoo0oco0coco0oo0o 0!” 


AAAAAABRAA 


0- 
0-3 
0-4 
0-1 
0 - 108 
-500 - 500 
-32768 - 32767 
-500 - 500 
-500 - 500 
0 - 65535 
0 - 65535 
0-127 
0 - 4095 
0 - 4095 
0 - 4095 
0 - 4095 
0 - 4095 
0 - 4095 
0-255 
0 - 255 
-32768 - 32767 
-32768 - 32767 
-32768 - 32767 


DADA AAAAAIAAIAIAAAAIAAAAAIAAIAIAIAIAIAIAIAARARARAARAAA 


16 On ee One en men ion men mmen| 


1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
2 
2 
1 
2 
2 
1 
2 
2 
2 
2 
2 
2 
2 
1 
2 
1 
1 
1 
1 
1 
2 
2 
2 
2 
2 
2 
1 
2 
2 
2 
2 
2 
2 
1 
1 
2 
2 
2 
2 
1 


